timers: take the event loop ref in Immediate.ref() only while the Immediate is queued - #48576

Where it came from. A generated program that mixes ref() and unref() on Immediates did not end on bun and ended on Node. Review of #30069 had named the same gap (unref(); ref() inside a setImmediate callback) and left it for a follow-up that aligns _destroyed for Immediates. The two repro shapes exit on bun 1.2.9 and hang on 1.2.10.

How long the ref stays. deinit() gives the ref back when the wrapper is collected. So the process stays alive for good while the handle is reachable: the script above as an ES module or with bun -e was still running after 60 s on main. As a CommonJS file, where nothing holds a after the module body, it exited after about 11 s. In a Worker the worker had not exited after 45 s on main, and it exits here.

Measurements. Two release builds from one toolchain: main 89452d2 and this change. Instruction counts come from gdb (nexti inside the function, or stepi until it returns), two equal runs each.

TimerObjectInternals stays 40 bytes. TimerFlags stays at 32 of 32 bits. The diff of EventLoopTimer.rs is one comment line.

Two earlier shapes of this change were dropped for cost. A pin of the wrapper before the kind branch in init() added 3 instructions per setImmediate() and 2 per setTimeout(). So init() is unchanged, and the assertion accepts the empty slot that init() has when it takes the ref. With the gate inline, LLVM stopped inlining do_ref into the two host functions, which added 18 instructions to every ref(). So the path after unref() is one out-of-line function.

A smaller shape that was not taken. Mark the removed Immediate cleared in run_immediate_task and keep the !get_destroyed() test in do_ref. That needs no new function. It makes _destroyed true for an Immediate that bun removed unrun, where Node prints false, and it adds a store to the path of every cleared Immediate.

The assertion. It reads the same pin as the gate, so it catches a future call site that enables the ref without the gate. It does not catch a pin that no longer matches the queue.

Probes against Node v26.3.0. 26 scripts that mix ref(), unref(), clearImmediate, beforeExit, uncaughtException, a Worker and timers. On main 17 print something else than Node, and in 11 the loop is still held when the guard timer of the script fires or at the 6 s limit. With this change 8 differ and none of the 26 hangs. The 8 are:

• ref() on an Immediate that bun removed unrun, 4 scripts. One of them matched Node on main: it called unref() again at once.
• An unref'ed Immediate that never runs where Node runs it, with no ref() involved, 2 scripts.
• Timeout.hasRef() after the timer fired or was cleared, 2 scripts. Node keeps the last ref()/unref() state. timers: Timeout.hasRef() reports the sticky ref flag after clearTimeout #34082 changed that and closed unmerged.

Each clause has a failing test. On debug builds with one clause removed:

• Without the pin read: the beforeExit test fails. The child aborts with panic: an Immediate that left the queue took an event loop ref.
• With in_callback set from the immediate queue again: the 8 script rows and "is true during the callback of an immediate" fail on the _destroyed value. No row hangs, so the in_callback move can be split out if the _destroyed change is not wanted.
• Without !fake(): "ref() inside the callback of a faked Immediate takes the ref" fails. That test passes on main too. It pins the timer heap behaviour of a faked Immediate.

Suites. Release builds, main against this change, node-timers.test.ts plus all of test/js/web/timers/ plus fake-timers.test.ts: 610 pass and 10 fail on main, 620 pass and 0 fail here. Debug (ASAN) build: node-timers.test.ts 44 of 44, setTimeout.test.js, setImmediate.test.js, fake-timers.test.ts 497 of 497, 56 vendored test-timers-*.js, test-process-ref-unref.js. On the debug build timer-gc-roots.test.ts has 2 tests and setInterval.test.js has 1 test that exceed their time limits. Their fixtures finish with the right output without the limit, they do not use setImmediate, and both files pass on the two release builds.

The tests spawn with timeout. bun test does not kill the child of a concurrent test that times out, so a failing run without it leaves hung children.

Still unlike Node after this change.

• bun drops an unref'ed Immediate when nothing holds the loop at the moment it is reached. A ref'ed Immediate that already ran in the same batch no longer counts, so setImmediate(a); setImmediate(b).unref() runs only a, where Node runs both in one pass. For the same reason timers/promises setImmediate(v, { ref: false }) behind a plain setImmediate does not settle. When nothing else holds the loop, Node keeps the Immediate queued and runs it if beforeExit revives the loop.
• Two shapes that never exit and do not go through ref() are unchanged: a beforeExit listener that queues an unref'ed Immediate, and a top-level await of setImmediate(v, { ref: false }).
• Timeout.hasRef() after fire or clear (above).
• A faked Immediate (jest.useFakeTimers({ toFake: ["setImmediate"] })) keeps _destroyed === false and hasRef() === true inside its callback.

The first two need the drop rule in run_immediate_task and loop liveness (is_event_loop_alive) to change. That is a separate change.

Self-review. Four concerns. (1) The spawned children had no timeout, so a failing run left hung children: added. (2) The beforeExit test printed nothing after ref(): it now prints hasRef() after ref() and states what Node prints. (3) The comment above the gate cited Node's Immediate rule under a sentence about _destroyed, and the source did not say that ref() on a removed Immediate differs from Node: the comment now covers Timeouts only and two one-line comments cover Immediates. (4) "for good" was too strong: see "How long the ref stays". Declined: an in-process test of the removed Immediate. It passes only if nothing else holds the loop of the test runner, which the test does not control.

Merge order. #48149 and #44806 also edit fire_catching.

Windows. Not run. There the Immediate loop ref is a started uv_idle handle (increment_immediate_ref), which keeps uv_run from sleeping in poll. So by reading, the leaked ref on main also keeps the loop busy there.